---
title: Build Plugin
description: A guide on how to use the optional build plugin for TypeGPU
---

[unplugin-typegpu](https://www.npmjs.com/package/unplugin-typegpu) is an optional (but highly recommended) tool for projects using TypeGPU. It hooks into your bundler of choice, and unlocks new features, optimizations and quality-of-life improvements.

The package includes the following functionalities:

- **TypeGPU functions implemented in JS/TS**

  The plugin allows transpiling a subset of JavaScript to WebGPU Shading Language (WGSL).
  The parsing of JavaScript happens ahead of time, emitting a highly compact AST format, called [tinyest](https://www.npmjs.com/package/tinyest).

  ```ts
  import tgpu from 'typegpu';
  import * as d from 'typegpu/data';

  // Found by the plugin and decorated with 'tinyest' metadata
  const add = (a: number, b: number) => {
    'use gpu';
    return a + b;
  };
  ```

  Besides parsing JS into an AST, the plugin also collects external references, so it is not necessary to pass them to the `$uses` method (as is required when implementing functions in WGSL).

- **Automatic naming of tgpu objects**

  Naming TypeGPU resources via the `$name` method is very helpful for debugging, but it can get very repetitive.
  Instead, the plugin is able to automatically name each resource based on the variable names that they are assigned to.

## Installation

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs syncKey="package-manager">
  <TabItem label="npm" icon="seti:npm">
    ```sh frame=none
    npm install --save-dev unplugin-typegpu
    ```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
    ```sh frame=none
    pnpm add -D unplugin-typegpu
    ```
  </TabItem>
  <TabItem label="yarn" icon="seti:yarn">
    ```sh frame=none
    yarn add -D unplugin-typegpu
    ```
  </TabItem>
</Tabs>

After installing the package, the exported plugin needs to be included in the list of plugins in the bundler config.

## Supported bundlers

The plugin was built using [unplugin](https://unplugin.unjs.io/), which allows it to be used with a variety of bundlers.
Currently, the package exports plugins for the following ones: _esbuild_, _farm_, _rolldown_, _rollup_, _rspack_, _vite_, _webpack_.
Apart from the tools supported by _unplugin_, a _babel_ plugin was also created.

:::caution
The _babel_ and _vite_/_rollup_ plugins are the ones that are actively being maintained and tested by the TypeGPU team,
the stability of the other ones may be limited.
:::

- Vite

```js title="vite.config.js"
import { defineConfig } from 'vite';
import typegpuPlugin from 'unplugin-typegpu/vite';

export default defineConfig({
  plugins: [typegpuPlugin({})],
});
```

- Babel (React Native)

```js title="babel.config.js"
module.exports = (api) => {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['unplugin-typegpu/babel'],
  };
};
```

## Plugin options

```ts
interface Options {
  /** @default [/\.m?[jt]sx?$/] */
  include?: FilterPattern;
  /** @default undefined */
  exclude?: FilterPattern;
  /** @default undefined */
  enforce?: 'post' | 'pre' | undefined;
  /** @default undefined */
  forceTgpuAlias?: string;
  /** @default true */
  autoNamingEnabled?: boolean;

  /**
   * Skipping files that don't contain 'typegpu', 'tgpu' or 'use gpu'.
   * In case this early pruning hinders transformation, you
   * can disable it.
   *
   * @default true
   */
  earlyPruning?: boolean | undefined;
}
```

The plugin accepts the standard `unplugin` options, that make it possible to customize which files are to be processed ([include/exclude](https://rolldown.rs/guide/plugin-development#plugin-hook-filters) patterns),
or [enforce](https://vite.dev/guide/api-plugin.html#plugin-ordering) the order in which the plugin is run in regards to other plugins.

The custom _forceTgpuAlias_ option allows specifying the name of _tgpu_ object imported from `typegpu`.
It is only useful in a handful of custom scenarios, when the name cannot be retrieved by the plugin automatically from the import statement.

## Further reading

For more information about bundler plugins, please refer to the [unplugin](https://unplugin.unjs.io/guide/) and [babel](https://babeljs.io/docs/plugins) documentations.
